home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / archiver / zoo21src.zoo / options.doc < prev    next >
Text File  |  1991-07-14  |  17KB  |  322 lines
  1. /* derived from: options.doc 1.4 88/08/22 15:24:59 */
  2. /* $Source: g:/newzoo\rcs\options.doc $ */
  3. /* $Id: options.doc 1.1 1991/07/14 22:39:26 bjsjr Exp $ */
  4.  
  5. Documentation about the file options.h.
  6.  
  7. The file options.h defines various symbols and macros that are needed
  8. to ensure system-independence.  The basic philosophy is to use a
  9. distinct symbol for each attribute that varies from machine to machine.
  10. Then, for each new system, we define symbols corresponding to its
  11. attributes. Thus, ideally, the only place in Zoo code that we actually
  12. use the name of a machine is in this file, in portable.h, and possibly in
  13. machine.h and options.c.  Everywhere else in the code we only use
  14. names of attributes.
  15.  
  16. LOOK IN THE FOLLOWING FILES WHEN MAKING CHANGES TO SUPPORT A NEW SYSTEM:
  17.  
  18.       options.h, portable.h, machine.c
  19.  
  20. ALSO GLANCE AT THESE FILES TO MAKE SURE THEY WILL WORK:
  21.  
  22.       zooio.h, machine.h
  23.  
  24. Machine names:
  25.  
  26. MSC         Microsoft C under MS-DOS      (not currently in use)
  27. TURBOC      Turbo C++ 1.0 under MS-DOS    (works, compiled version is
  28.                                           separately distributed)
  29. SYS_V       Most releases of System V     (works)
  30. VMS         VAX/VMS 5.4                   (works, stream-LF files only)
  31. BSD4_3      4.3BSD an most derivatives    (works)
  32. MCH_AMIGA   AmigaDOS Aztec/Manx C         (not tested; compiled version
  33.                                                          will eventually follow)
  34.  
  35.  
  36. MERGED OR MIXED SYSTEMS.  Many vendors of **IX systems take one of the
  37. two (System V or BSD) and add features from the other.  In some cases
  38. they do a terrible job of reconciling irreconcilable differences between
  39. the two, such that the merged system will now compile neither System V
  40. stuff nor BSD stuff.  If you are dealing with such a system, try 
  41. compiling with both BSD4_3 and SYS_V in turn, and see if one of them
  42. works.  If not, then go through the list of compilation symbols below
  43. and pick a set that matches your system.
  44.  
  45. ------------------------------------------------------------------------
  46. NOTE:  The term "zoofile" below refers to an open file of type
  47. ZOOFILE.  Currently this is defined to be equivalent to a standard
  48. buffered file pointer of type "ZOOFILE *" but this could change in the
  49. future.  Dependence on exact definition of ZOOFILE is localized to a
  50. few files:  options.h, portable.h, portable.c, and machine.c.
  51. ------------------------------------------------------------------------
  52.  
  53. Attributes of systems:
  54.  
  55. CHEKDIR
  56.    Test each supplied filename and if it is a directory or other special
  57.    type of file, do not try to add it to an archive.  If CHEKDIR is
  58.    defined, then machine.c must also contain function isadir() that
  59.    tests a supplied zoofile and returns 1 if it corresponds to a
  60.    directory or other special type of file, else 0.
  61. CHEKUDIR
  62.    Like CHEKDIR but use function isuadir() that tests a pathname, not
  63.    a zoofile.  Both CHEKDIR and CHEKUDIR may be defined, if both
  64.    functions isadir() and isuadir() are available;  in this case
  65.    zoo code will use both and will execute slightly faster.
  66.    (However, simultaneous definition of CHEKDIR and CHEKUDIR has
  67.    not been tested.)
  68. DISK_CH
  69.    If defined, must hold the value of a character that separates a
  70.    disk name from the rest of the pathname.  All characters up to and
  71.    including this character will be removed from a pathname before it
  72.    is stored in an archive.  Usually a colon (':').
  73. EXISTS
  74.    If defined, is assumed to be a macro that accepts a filename and
  75.    returns an int value of 1 if the file exists and 0 if it doesn't.
  76.    If not defined, existence of files is tested by attempting to open
  77.    them for read or write access.
  78. FATTR
  79.    If defined, file attributes will be preserved.  A function
  80.    getfattr(f) must also exist that returns the attributes of a
  81.    zoofile f (or of a pathname f, if the symbol FATTR_FNAME is
  82.    also defined); and a function setfattr(f, a) must exist that
  83.    sets the attributes of a file with pathname f to the value a.
  84.    For more details see the source code in sysv.c and bsd.c.  Currently
  85.    the attribute value a is required to be in the zoo portable
  86.    format.  The lowest nine bits of this format correspond to
  87.    the **IX mode bits described for chmod(2) and these are the only
  88.    bits currently used.
  89. FATTR_FNAME
  90.    If defined, and if FATTR is also defined, zoo code will
  91.    obtain the attributes of a file by calling the function
  92.    getfattr(f) and supplying it with filename f.  If FATTR_FNAME
  93.    is not defined, then getfattr(f) is supplied a zoofile f.
  94. ANSI_PROTO
  95.    Use ANSI-style function prototypes declarations.
  96. VOIDPTR
  97.    The type of a generic pointer, as returned by malloc().  This
  98.    should be defined as void * in an ANSI C environment.  In most
  99.    other environments it will be char *.
  100. LINT
  101.    If defined, SCCS identifier strings will not be included in the
  102.    generated code.  This will make the code smaller and will also
  103.    avoid complaints from lint about unused variables.  This symbol
  104.    should be defined in the Makefile, NOT in `options.h', otherwise
  105.    it will not be fully effective.
  106. FOLD
  107.    Fold filenames to lowercase.  Define this for case-insensitive filesystems
  108. FPUTCHAR
  109.    If defined, a library function fputchar() is assumed available
  110.    that is like fput() but is a function, not a macro, to save
  111.    space.  If not defined Zoo uses its own fputchar() function.
  112. PORTABLE
  113.    Use portable functions --- define for every system except MS-DOS
  114. PURIFY
  115.    When filenames are being read from standard input, ignore all
  116.    characters begining with the first blank or tab encountered.
  117.    This will allow filenames to be fed from a program that produces
  118.    lines containing filenames followed by other information that
  119.    should be ignored.  Should be defined for most non-**IX systems.
  120. DONT_SORT
  121.    Don't sort filename arguments -- files will be stored in the
  122.    exact order in which names are supplied on the command line.
  123.    Not currently used for any system, but could be used if memory
  124.    is really tight.
  125. NOENUM
  126.    Compiler does not support enumerations
  127. FNLIMIT
  128.    Pathname length limit for this system
  129. NEEDCTYP
  130.    If defined, tells the code to include the header file ctype.h for
  131.    use by character conversion macros.  If and only if NEEDCTYP is not
  132.    defined, macros or appropriate function declarations can be put in
  133.    portable.h.  Zoo uses isupper(), isdigit(), toascii(), and tolower().
  134.    If NEEDCTYP is not defined, the symbol USE_ASCII can be defined to
  135.    cause zoo to assume the ASCII character set and use its own isupper(),
  136.    isdigit(), toascii(), and tolower() functions, possibly making the
  137.    executable code smaller.
  138. USE_ASCII
  139.    See description of NEEDCTYP.  USE_ASCII should not be defined if
  140.    NEEDCTYP is defined, else there may be conflicts between macro
  141.    and function names.
  142. NIXTIME
  143.    If defined, a function setutime() must be defined that will set the
  144.    date and time of a file whose pathname is supplied.  If not defined,
  145.    a function settime() must be defined that will do the same for
  146.    a zoofile.
  147. GETUTIME
  148.    If defined, a function getutime() must be defined that will return
  149.    the MS-DOS format date and time of the specified filename.  If this
  150.    symbol is not defined, then a function gettime() must be defined
  151.    that will do the same for a zoofile instead of a filename.
  152. NOSIGNAL
  153.    Don't use signals because library doesn't support them
  154. T_SIGNAL
  155.    The data type returned by a signal handler.  Historically
  156.    "int", but "void" in ANSI C.
  157. PATH_CH
  158.    The character that separates the directory name from the filename
  159.    in a pathname.  String value.
  160. PATH_SEP
  161.    The set of characters that may separate preceding directory/device
  162.    information from the filename.  String value.
  163. EXT_SEP is the union of PATH_SEP and the set of characters separating a
  164.    filename extension from the rest of the filename.  String value.
  165. EXT_CH
  166.    Character that separates base part of filename from extension.
  167.    Char value.
  168. NEED_MEMSET  If defined, zoo will define its own equivalent of memset().
  169.     if not defined, zoo will t